package com.aleyn.annotation

/**
 * @author: Aleyn
 * @date: 2023/6/13 15:41
 *
 * 路由路径注解，用于定义一个可导航组件的地址。
 *
 * 这是 LRouter 框架最核心的注解之一。通过在 `Activity`、`Fragment` 或其他可处理路由的类上
 * 添加此注解，你可以为该组件分配一个唯一的、类似 URL 的路径。之后，你就可以通过这个路径
 * 从应用内的任何地方发起导航请求，跳转到该组件。
 *
 * 工作原理：
 * 1. 编译期间，KSP 会扫描所有被 `@Route` 注解的类。
 * 2. 处理器将路径（`path`）与对应的组件类（`Activity`、`Fragment` 等）进行映射。
 * 3. 这些映射关系被收集并生成到一个路由表中。
 * 4. 运行时，LRouter 根据请求的路径在路由表中查找对应的组件，然后执行跳转。
 *
 * 使用示例：
 * ```kotlin
 * // 为 UserProfileActivity 定义一个路由路径
 * @Route(path = "/user/profile", desc = "用户个人资料页")
 * class UserProfileActivity : AppCompatActivity() { ... }
 *
 * // 在应用的任何地方，通过路径发起跳转
 * LRouter.getInstance().build("/user/profile").navigation()
 *
 * // 路径中也可以携带参数，但这通常用于声明默认参数，更推荐在 `build()` 时动态添加
 * @Route(path = "/user/detail?userId=123")
 * class UserDetailActivity : AppCompatActivity() { ... }
 * ```
 *
 * @param path 路由地址。必须是唯一的字符串，通常采用 `/group/page` 的形式。
 *             路径可以包含查询参数（`?key=value`），但这只应作为默认值或静态参数，
 *             动态参数建议通过 `Postcard.withString()` 等方法在跳转时传递。
 * @param desc 对当前路由页面的简要描述。此信息主要用于文档、日志或开发工具，方便开发者理解页面功能。
 * @param other 预留的整型标识字段。可用于定义一些特殊的路由标志，例如页面类型、需要的权限等级等。
 *              具体如何使用由业务场景决定。在 LRouter 核心库中，它被用作 `RouteMeta.extra`。
 */
@Retention(AnnotationRetention.SOURCE)
@Target(AnnotationTarget.CLASS, AnnotationTarget.ANNOTATION_CLASS)
annotation class Route(
    /**
     * 路由地址，必须是唯一的。
     * 格式如："/group/page" 或 "/group/page?key=value"。
     */
    val path: String,

    /**
     * 对当前路由页面的简要描述，方便开发者理解。
     */
    val desc: String = "",

    /**
     * 预留的整型标识字段，可用于定义特殊标志，如页面类型、权限等级等。
     */
    val other: Int = 0
)
